Sparking Joy in Docs

Write good docs#

The highest impact way a developer can spark joy is in writing good docs. It is the first thing every new user and teammate reads, and it shows that you care about the project.

You don’t have to create a bells-and-whistles docs site for every little project. For most things, a really good README is more than enough. However, you can do a lot to “sweat the README.”

Get straight to the point#

Place installation, examples, and API docs upfront and use a Table of Contents generator to make them easy to navigate. Keep them up to date and write example code with the understanding that developers will copy and paste while skimming over most of the explanations. Even where copy and paste are not possible, like when developer keys are concerned, you can show the expected form of the key for people to visually verify that they have the right one, e.g., API_TOKEN= #, e.g., MY_API_TOKEN_1234

Tip: In the Node.js ecosystem, dotenv-safe is helpful for enforcing checks that environment variables are specified properly.

Add appropriate license#

Licenses matter in open source. Some legal interpretations don’t allow developers to even look at unlicensed code, much less use or contribute to it. Learn the difference between copyright and copyleft, and pick a license that reflects your values. More importantly, don’t use software that might compromise your company’s intellectual property.

You can use tldrlegal to understand licenses or rely on approved licenses from the Open Source Initiative. If in doubt, use MIT. It takes seconds to add a license through a CLI (npx license mit) or GitHub’s UI. Make it a habit!

Add badges#

CI Badges are associated with quality. It’s tempting to regard doc badges as performative “pieces of flair,” but an academic study of this phenomenon has actually found that badges with underlying analyses, like displaying build status, issue resolution times, and code coverage, are predictive of project quality. Shields.io makes it easy to set up a selection of great badges.

Correlation isn’t causation; this probably has more to do with the kind of maintainer that adds badges than implying that badges cause project quality. You can be the kind of maintainer that shows they care!

Side note: Not too many badges! four to six badges seem like the sweet spot— any more, and the “Christmas Tree” effect starts showing you are “trying too hard.”

Give proper attention to repo metadata#

Repo Metadata should also be given proper attention. GitHub allows you to place a description of the project at the top and place a link. Be sure to put your best one-liner pitch in there and to link to a live project of the demo! This is literally the first-place developers look.

Add READMEs#

READMEs are typically written in Markdown, which imposes some strict order on your content. However, you can often break this monotony by using some HTML alignment with <div align="center"> or adding a logo or banner (either ask for contributions or use a generator like Hipster Logo Generator, Hatchful, or Excalidraw).

Pay attention to structure and weight#

Pay attention to the structure and relative weight of your documentation. Nobody enjoys reading big blocks of text; break it up into bullet points or tables where possible. With GitHub-flavored Markdown, you can even hide lengthy explanations of edge cases in HTML <details> and <summary> tags interspersed with Markdown, which helps make your docs useful for both the skimmer and the dev who wants to dig deeper.

Automate formatting#

Automate formatting for your docs. You can run prettier as a git hook (with husky and pretty-quick for a fast experience) and use doctoc to keep your table of contents up to date (This also available as a GitHub action.).

Add illustrations#

Sometimes, a picture speaks a thousand words. Feature screenshots or a demo gif if possible. For “How it Works” sections, you can also create simple ASCII diagrams using tools like ASCII Flow and Monodraw to explain systems and concepts. You can even use free drawing tools like Excalidraw, Draw.io (in VS Code too!), and Miro to illustrate with color.

“I swear by the README.md SVG logo. No matter how good/bad the code is, you put a logo on there, and I’ll probably npm install it.”

- Matt Hova (somewhat joking)

There’s no end to things you can add for great documentation, so it is best to match your documentation to the project maturity. Two nice features that are always appreciated are searchability and a “Trade offs,” or “When NOT to use this,” section.

Anecdote time#

Great docs aren’t only important for open source marketing and adoption. One of my best dev memories was hearing a new employee coming across an internal repo for the first time and finding an extensively well-explained README with diagrams to show how everything worked and even a short explanation of project file structure. The engineer responsible for it hadn’t touched the repo in over a year, but the new person was able to pick it up right away. You BET the new person was overjoyed to find such great docs and sang its praises all over the company’s internal chat. As for the original engineer? She was promoted to Principal Backend Engineer not long after.